Docs: Mention the [[example]] section

Expand documentation on integration tests

Docs: Clarify what `cargo test` compiles vs. runs

Auto merge of #2097 - alexcrichton:dont-panic-when-slicing, r=huonw

Closes #2094

Don't panic when printing the precise source id

Closes #2094

Auto merge of #2092 - gkoz:lock_line_endings, r=alexcrichton

Before writing the lockfile read the existing one and

 * detect the line endings style, fixes #2076, #1722;
 * compare the contents to avoid redundant overwriting.

Detect the line endings convention of Cargo.lock (CRLF or LF) and preserve it

Fixes #2076

Avoid overwriting the lockfile if there are no changes

Auto merge of #2093 - alexcrichton:bump, r=alexcrichton

Bump to 0.7.0

Add a test for #2076, preservation of line endings style

Auto merge of #2070 - alexcrichton:test-optional, r=brson

Previously a warning was issued if both -p and --features were passed as flags,
and the rationale for this was that if --features modified the activated set of
features in the package selected by -p it would alter Cargo.lock, which is
undesirable as Cargo.lock should be stable.

This commit, however, interprets --features as changing the resolved graph of
the top-level package, and then -p is a query on that resolved graph. This way
the Cargo.lock file never changes and you're allowed to test optional
dependencies.

Closes #2083

Auto merge of #2077 - Lechindianer:master, r=alexcrichton

Just a simple fix

Fixed typo

Auto merge of #2061 - alexcrichton:update, r=alexcrichton

* Move along the same rails for all dependencies, picking up various small perf,
  build, and portability improvements.
* Update pinned rustc to pick up perf improvements and such
* Tweak expected error message from tests to continue to work

Update dependencies

* Move along the same rails for all dependencies, picking up various small perf,
  build, and portability improvements.
* Update pinned rustc to pick up perf improvements and such
* Tweak expected error message from tests to continue to work

Auto merge of #2071 - aarzee:master, r=alexcrichton

Whitespace: remove leading newlines; replace lines containing only whitespace with empty lines; replace multiple trailing newlines with a single newline; remove trailing whitespace in lines.

Images: Compress PNG files with zopflipng, JPG files with mozjpeg jpegtran, and GIF files with gifsicle.

This PR was created semiautomatically.

Auto merge of #2072 - durka:patch-2, r=alexcrichton

fix copy/paste error in doc

Cleanup

Whitespace: remove leading newlines; replace lines containing only whitespace with empty lines; replace multiple trailing newlines with a single newline; remove trailing whitespace in lines. Images: Compress PNG files with zopflipng, JPG files with mozjpeg jpegtran, and GIF files with gifsicle.

Allow testing optional dependencies

Previously a warning was issued if both -p and --features were passed as flags,
and the rationale for this was that if --features modified the activated set of
features in the package selected by -p it would alter Cargo.lock, which is
undesirable as Cargo.lock should be stable.

This commit, however, interprets --features as changing the resolved graph of
the top-level package, and then -p is a query on that resolved graph. This way
the Cargo.lock file never changes and you're allowed to test optional
dependencies.

Auto merge of #2068 - alexcrichton:root-profiles, r=brson

When testing or building multiple packages via the `-p` argument the root
package's profiles should always be used instead of the sub-package's set of
profiles.

Always use the root package's set of profiles

When testing or building multiple packages via the `-p` argument the root
package's profiles should always be used instead of the sub-package's set of
profiles.

Auto merge of #2067 - apasel422:spell, r=alexcrichton

Correct spelling in docs

Auto merge of #2062 - aarzee:master, r=steveklabnik

Remove leading newlines; replace lines containing only whitespace with empty lines; replace multiple trailing newlines with a single newline; remove trailing whitespace in lines.

This PR was created semiautomatically.

Clean whitespace

Remove leading newlines; replace lines containing only whitespace with empty lines; replace multiple trailing newlines with a single newline; remove trailing whitespace in lines

Auto merge of #2026 - alexcrichton:cargo-install, r=brson

This commit is an implementation of [RFC 1200][rfc] which brings two new
subcommands: `cargo install` and `cargo uninstall`. Most of this is a straight
implementation of the RFC, but a few tweaks were made:

* The `-p` or `--package` arguments are no longer needed as you just pass
  `crate` as a bare argument to the command, this means `cargo install foo`
  works and downloads from crates.io by default.
* Some logic around selecting which crate in a multi-crate repo is installed has
  been tweaked slightly, but mostly in the realm of "let's do the thing that
  makes sense" rather than the literal "let's do what's in the RFC".
  Specifically, we don't pick a crate with examples if there are multiple crates
  with binaries (instead an error is generated saying there are multiple binary
  crates).

[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1200-cargo-install.md

Finish implementing `cargo install`

This commit is an implementation of [RFC 1200][rfc] which brings two new
subcommands: `cargo install` and `cargo uninstall`. Most of this is a straight
implementation of the RFC, but a few tweaks were made:

* The `-p` or `--package` arguments are no longer needed as you just pass
  `crate` as a bare argument to the command, this means `cargo install foo`
  works and downloads from crates.io by default.
* Some logic around selecting which crate in a multi-crate repo is installed has
  been tweaked slightly, but mostly in the realm of "let's do the thing that
  makes sense" rather than the literal "let's do what's in the RFC".
  Specifically, we don't pick a crate with examples if there are multiple crates
  with binaries (instead an error is generated saying there are multiple binary
  crates).

[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1200-cargo-install.md

Basic work for cargo install

Auto merge of #2060 - sorear:broken-links, r=huonw

The semver documentation doesn't seem to be hosted anywhere at the moment so I made that link point at GitHub.

Fix broken links in documentation

Auto merge of #2055 - alexcrichton:rustdoc-race, r=brson

Cargo will run rustdoc concurrently if it can, and rustdoc is instructed to
place output in a central location. Rustdoc itself knows how to handle
concurrent invocations, but it requires that the output location exists for this
to work correctly (as otherwise the rustdoc processes will race to create the
directory). While this may also be fixable upstream, for now just precreate the
doc directory to ensure that rustdoc doesn't race trying to create it.

Auto merge of #2053 - gkoz:run_human_error, r=alexcrichton

Closes #1516

Auto merge of #2037 - honorabrutroll:master, r=alexcrichton

Addresses issue #376 by checking the compilation mode before printing.

Differentiates documentation and compilation in user output

Fix tests to work with new jobqueue

Wrap `cargo run` `ProcessError` in `Human` if the exit code is non-zero

Pre-create the output doc directory

Cargo will run rustdoc concurrently if it can, and rustdoc is instructed to
place output in a central location. Rustdoc itself knows how to handle
concurrent invocations, but it requires that the output location exists for this
to work correctly (as otherwise the rustdoc processes will race to create the
directory). While this may also be fixable upstream, for now just precreate the
doc directory to ensure that rustdoc doesn't race trying to create it.

Clarify the default `cargo run` error message on a non-zero exit code

The behavior is the same in the default and verbose modes now:
 - the default mode will not suggest re-running with `--verbose`
 - the verbose mode will not print the binary name.

Add `cargo run` exit_code_verbose test

Auto merge of #2052 - rgardner:add-wildcard-end-date-to-faq, r=alexcrichton

This adds a bolded message to the FAQ clarifying the last date crates.io
will accept crates with wildcard dependencies.

Closes rust-lang/crates.io#200

Add crates.io wildcard end date to FAQ

This adds a bolded message to the FAQ clarifying the last date crates.io
will accept crates with wildcard dependencies.

Closes rust-lang/crates.io#200

Auto merge of #2050 - gkoz:build_cfgs, r=alexcrichton

Fixes #1980

Propagate custom cfg directives to rustdoc, fixes #1980

Store all cfgs in Compilation instead of features only

Add features test to cardo doc tests

Add tests for passing cfg directives when building tests and rustdoc

Reproduces #1980

Auto merge of #2048 - alexcrichton:build-script-fresh, r=brson

This commit causes a recompile to be triggered if the overridden version of a
build script changed since it was last run. Previously this wasn't tracked very
well due to fingerprints not accounting for the right data.

There are a few architectural changes here which were made to prepare for this:

* The unit of work for "running a build script" is now emitted as dependency
  regardless of whether a build script is overridden or not. Previously it was
  omitted if overridden.
* This unit of work has 0 dependencies if it is overridden (as we know the
  output) and otherwise has the normal set of dependencies.
* The fingerprint calculation was updated to recognize when a build script
  execution is overridden and instead consider the overridden value as input to
  the fingerprint. This means that if the overridden values change they will
  trigger a recompile.
* The "prepare a build script to run" step now emits a noop if the execution of
  the build script is overridden.

After putting all that together, this commit ...

Closes #2042

Fix recompiles where overrides changed

This commit causes a recompile to be triggered if the overridden version of a
build script changed since it was last run. Previously this wasn't tracked very
well due to fingerprints not accounting for the right data.

There are a few architectural changes here which were made to prepare for this:

* The unit of work for "running a build script" is now emitted as dependency
  regardless of whether a build script is overridden or not. Previously it was
  omitted if overridden.
* This unit of work has 0 dependencies if it is overridden (as we know the
  output) and otherwise has the normal set of dependencies.
* The fingerprint calculation was updated to recognize when a build script
  execution is overridden and instead consider the overridden value as input to
  the fingerprint. This means that if the overridden values change they will
  trigger a recompile.
* The "prepare a build script to run" step now emits a noop if the execution of
  the build script is overridden.

After putting all that together, this commit ...

Closes #2042

Auto merge of #2046 - gkoz:find_perm, r=alexcrichton

This is an improvement of fd781a12 adopted by rustc in https://github.com/rust-lang/rust/commit/f001f9a7
See also #822

Auto merge of #2044 - alexcrichton:fingerprint-better, r=brson

This helps diagnose "why did this rebuild" situations so not only the mtime is
known but also the file in question.

Ignore `*.py` in `make no-exes`

Auto merge of #2047 - akiss77:makefile-cfg-optimize, r=alexcrichton

Until now, there was a CFG_DISABLE_OPTIMIZE that controlled whether `--release` is passed to cargo during the build, and a CFG_ENABLE_OPTIMIZE that controlled where `make install` (among others) looked for the already built cargo executable. Unfortunately, if none of these were specified, `make all` built a release cargo but `make install` looked for it under `$(CFG_TARGET)/debug` (and aborted with "Please run `make` first"). This patch keeps CFG_DISABLE_OPTIMIZE only and uses it consistently.

Auto merge of #2045 - zv:master, r=alexcrichton

This pull request fixes two distinct issues with the `_cargo` compdef:

- Tab-completion should supply `--color=` options (`none`, `auto`, and `always`)
- Updates the deprecated "command scope flags" which now have a single, unambiguous representative variable which provides the appropriate exclusivity between options.

Fix the usage of CFG_xxxABLE_OPTIMIZE variables in Makefiles

Until now, there was a CFG_DISABLE_OPTIMIZE that controlled whether
`--release` is passed to cargo during the build, and a
CFG_ENABLE_OPTIMIZE that controlled where `make install` (among
others) looked for the already built cargo executable.
Unfortunately, if none of these were specified, `make all` built a
release cargo but `make install` looked for it under
`$(CFG_TARGET)/debug` (and aborted with "Please run `make` first").
This patch keeps CFG_DISABLE_OPTIMIZE only and uses it
consistently.

Use the more portable `find -perm` syntax

This is an improvement of fd781a12 adopted by rustc in https://github.com/rust-lang/rust/commit/f001f9a7
See also #822

Merge branch 'compdef_coloropts'

* compdef_coloropts:
  zsh compdef should supply color options

zsh compdef should supply color options

ZSH compdef should prompt to complete the options of
--color (auto|always|never)

Replace repeat options w/ command_scope_spec spec

Multiple commands accept these 'command scope specifiers', all of which
have had their argument completion definitions consolidated in this
variable which is expanded into the argument matchspec where appropriate.

`_arguments` util. function for build scope specs

Includes a shared and mutally exclusive build scope specifier for:
 * --bin
 * --example
 * --test
 * --lib
 * --bench

Include filename in path fingerprint

This helps diagnose "why did this rebuild" situations so not only the mtime is
known but also the file in question.

Auto merge of #2035 - alexcrichton:optimize-default, r=brson

This change mirrors the compiler by enabling optimizations by default rather
than by default producing an unoptimized Cargo build. I was curious why #2033
hit a debug assertion when we don't ship any binaries with debug assertions
enabled, but it looked like Cargo was installed via Homebrew which [does not
currently enable optimizations][homebrew]. I'll also send a PR over there, but I
figured it'd be also good to nip this in the bud and just start enabling
optimizations by default.

[homebrew]: https://github.com/Homebrew/homebrew/blob/5d09dd/Library/Formula/rust.rb#L69

Auto merge of #2040 - alexcrichton:dedupe, r=brson

I removed this in 68014ab8 thinking it wasn't necessary, which it technically
isn't for correctness but it ends up leading to absurdly long command lines to
the compiler for larger projects. This also changes the `Vec` to be a `BTreeSet`
to have sorting and deduplication as we go along which should be much faster
than waiting to sort until the very end.

Don't test SSL errors on OSX

Due to libgit2 perhaps using different frameworks it's a little too onerous to
test there. It's also pretty unlikely that libgit2 is configure to *not* have
SSL on OSX by mistake.

Auto merge of #2032 - alexcrichton:output-asap, r=brson

This can help debug some situations if an error happens parsing the output.

Auto de-dupe build scripts to link

I removed this in 68014ab8 thinking it wasn't necessary, which it technically
isn't for correctness but it ends up leading to absurdly long command lines to
the compiler for larger projects. This also changes the `Vec` to be a `BTreeSet`
to have sorting and deduplication as we go along which should be much faster
than waiting to sort until the very end.

Auto merge of #2038 - zv:master, r=alexcrichton

The existing zsh completion script refers to deprecated options for initializing a new cargo package with version control (`--(no-)git` & `--hg`). This PR removes these old options and adds a new completion option `--vcs` which accepts either `git`, `hg` or `none` as it's own options.

Added `none` option to --vcs

Remove deprecated --no-git & --hg options

Replace --git with --vcs [git|hg]

Auto merge of #2036 - alexcrichton:update-build-tools, r=alexcrichton

* Updates git2-rs back to 0.3 now that the distribution issue on OSX has been
  fixed.
* Updates libgit2-sys to using the `cmake` crate so building with VS 2015 can
  work.

Enable optimizations by default

This change mirrors the compiler by enabling optimizations by default rather
than by default producing an unoptimized Cargo build. I was curious why #2033
hit a debug assertion when we don't ship any binaries with debug assertions
enabled, but it looked like Cargo was installed via Homebrew which [does not
currently enable optimizations][homebrew]. I'll also send a PR over there, but I
figured it'd be also good to nip this in the bud and just start enabling
optimizations by default.

[homebrew]: https://github.com/Homebrew/homebrew/blob/5d09dd/Library/Formula/rust.rb#L69

Update some build tools and libgit2

* Updates git2-rs back to 0.3 now that the distribution issue on OSX has been
  fixed.
* Updates libgit2-sys to using the `cmake` crate so building with VS 2015 can
  work.
* Update pkg-config to totally disable it on MSVC (basically guaranteed to never
  work)

Auto merge of #2034 - alexcrichton:update-toml, r=alexcrichton

Closes #2031
Closes #2033

Update TOML dependency

Closes #2031
Closes #2033

Write the build script output ASAP

This can help debug some situations if an error happens parsing the output.

Auto merge of #2022 - alexcrichton:refactor, r=brson

This series of commits performs two primary tasks:

* The backend is refactored (again!) to have a much better understanding of what's used as input to everything else in terms of parallelization and dependency tracking. The major goal here was to completely unify all parts of the backend which sort of ad-hoc track dependencies and deal with cross compilation. More details can be found in the first commit message.
* Greatly improving diagnostics for why a crate is being rebuilt. This still requires setting `RUST_LOG`, but it was spurred on by #2011 and should help at least my own personal internal debugging of "why is this crate rebuilding?" which seems to come up quite often!

Auto merge of #2029 - aarzee:clean, r=alexcrichton

Remove leading newlines; replace lines containing only whitespace with empty lines; replace multiple trailing newlines with a single newline

Clean whitespace

Remove leading newlines; replace lines containing only whitespace with
empty lines; replace multiple trailing newlines with a single newline

Auto merge of #2028 - aarzee:master, r=alexcrichton

regex-synatx -> regex-syntax

Drop 1.1.0 as crossbeam needs `const fn`

To parse at least

Don't bother sorting build scripts

Turns out the tests don't actually need this "more deterministic" output and it
was also showing up relatively high in profiles (e.g. ~15% of a noop runtime) so
if this is necessary let's find a better way!

Add better diagnostics for rebuilding

This commit overhauls how a `Fingerprint` is stored on the filesystem and
in-memory to help provide much better diagnostics as to why crates are being
rebuilt. This involves storing more structured data on the filesystem in order
to have a finer-grained comparison with the previous state. This is not
currently surfaced in the output of cargo and still requires
`RUST_LOG=cargo::ops::cargo_rustc::fingerprint=info` but if it turns out to be
useful we can perhaps surface the output.

There are performance considerations here to ensure that a noop build is still
quite speedy for a few reasons:

1. JSON decoding is slow (these are just big structures to decode)
2. Each fingerprint stores all recursive fingerprints, so we can't just "vanilla
   decode" as it would decode O(n^2) items
3. Hashing is actually somewhat nontrivial for this many items here and there,
   so we still need as much memoization as possible.

To ensure that builds are just as speedy tomorrow as they are today, a few
strategies are taken:

* The same fingerprint strategy is used today as a "first line of defense" where
  a small text file with a string contains the "total fingerprint" hash. A
  separately stored file then contains the more detailed JSON structure of the
  old fingerprint, and that's only decoded if there's a mismatch of the short
  hashes. The rationale here is that most crates don't need to be rebuilt so we
  shouldn't decode JSON, but if it does need to be rebuilt then the work of
  compiling far dwarfs the work of decoding the JSON.
* When encoding a full fingerprint as JSON we don't actually include any
  dependencies, just the resolved u64 of them. This helps the O(n^2) problem in
  terms of decoding time and storage space on the filesystem.
* Short hashes continue to be memoized to ensure we don't recompute a hash if
  we've already done so (e.g. shared dependencies).

Overall, when profiling with Servo, this commit does not regress noop build
times, but should help diagnose why crates are being rebuilt hopefully!

Closes #2011

Add helper functions for reading/writing whole files

Adds some helpful error text if an error happens as well

Refactor Cargo's backend, again!

This commit started out identifying a relatively simple bug in Cargo. A recent
change made it such that the resolution graph included all target-specific
dependencies, relying on the structure of the backend to filter out those which
don't need to get built. This was unfortunately not accounted for in the portion
of the backend that schedules work, mistakenly causing spurious rebuilds if
different runs of the graph pulled in new crates. For example if `cargo build`
didn't build any target-specific dependencies but then later `cargo test` did
(e.g. a dev-dep pulled in a target-specific dep unconditionally) then it would
cause a rebuild of the entire graph.

This class of bug is certainly not the first in a long and storied history of
the backend having multiple points where dependencies are calculated and those
often don't quite agree with one another. The purpose of this rewrite is
twofold:

1. The `Stage` enum in the backend for scheduling work and ensuring that maximum
   parallelism is achieved is removed entirely. There is already a function on
   `Context` which expresses the dependency between targets (`dep_targets`)
   which takes a much finer grain of dependencies into account as well as
   already having all the logic for what-depends-on-what. This duplication has
   caused numerous problems in the past, an unifying these two will truly grant
   maximum parallelism while ensuring that everyone agrees on what their
   dependencies are.

2. A large number of locations in the backend have grown to take a (Package,
   Target, Profile, Kind) tuple, or some subset of this tuple. In general this
   represents a "unit of work" and is much easier to pass around as one
   variable, so a `Unit` was introduced which references all of these variables.
   Almost the entire backend was altered to take a `Unit` instead of these
   variables specifically, typically providing all of the contextual information
   necessary for an operation.

A crucial part of this change is the inclusion of `Kind` in a `Unit` to ensure
that everyone *also* agrees on what architecture they're compiling everything
for. There have been many bugs in the past where one part of the backend
determined that a package was built for one architecture and then another part
thought it was built for another. With the inclusion of `Kind` in dependency
management this is handled in a much cleaner fashion as it's only calculated in
one location.

Some other miscellaneous changes made were:

* The `Platform` enumeration has finally been removed. This has been entirely
  subsumed by `Kind`.
* The hokey logic for "build this crate once" even though it may be depended on
  by both the host/target kinds has been removed. This is now handled in a much
  nicer fashion where if there's no target then Kind::Target is just never used,
  and multiple requests for a package are just naturally deduplicated.
* There's no longer any need to build up the "requirements" for a package in
  terms of what platforms it's compiled for, this now just naturally falls out
  of the dependency graph.
* If a build script is overridden then its entire tree of dependencies are not
  compiled, not just the build script itself.
* The `threadpool` dependency has been replaced with one on `crossbeam`. The
  method of calculating dependencies has quite a few non-static lifetimes and
  the scoped threads of `crossbeam` are now used instead of a thread pool.
* Once any thread fails to execute a command work is no longer scheduled unlike
  before where some extra pending work may continue to start.
* Many functions used early on, such as `compile` and `build_map` have been
  massively simplified by farming out dependency management to
  `Context::dep_targets`.
* There is now a new profile to represent running a build script. This is used
  to inject dependencies as well as represent that a library depends on running
  a build script, not just building it.

This change has currently been tested against cross-compiling Servo to Android
and passes the test suite (which has quite a few corner cases for build scripts
and such), so I'm pretty confident that this refactoring won't have at least too
many regressions!

Touch up docs and use inline table syntax

This performs a pass over the docs, touching up sections in a few places and
also moving everything to using inline table syntax by default (the favorted way
to add a dependency)

Auto merge of #2019 - phi-gamma:dot-path-fix, r=alexcrichton

When traversing the directory tree, cargo will omit paths that start
with a period character to avoid interfering with other software.
Unfortunately this also prevents a crate from being located in a
directory prefixed with a period. Address this by extending the test
against the traversal root that already guards Git submodules.

Fixes issue #1999 which was introduced with commit 11144645f..

Add test case for project root located in dotdir

Do not skip the root path if it's a dotdir

When traversing the directory tree, cargo will omit paths that start
with a period character to avoid interfering with other software.
Unfortunately this also prevents a crate from being located in a
directory prefixed with a period. Address this by extending the test
against the traversal root that already guards Git submodules.

Fixes issue #1999 which was introduced with commit 11144645f..

Auto merge of #2018 - alexcrichton:dox, r=steveklabnik

This performs a pass over the docs, touching up sections in a few places and
also moving everything to using inline table syntax by default (the favorted way
to add a dependency)

r? @steveklabnik

Touch up docs and use inline table syntax

This performs a pass over the docs, touching up sections in a few places and
also moving everything to using inline table syntax by default (the favorted way
to add a dependency)

Auto merge of #2015 - alexcrichton:fix-nightly, r=alexcrichton

Some output of failing tests have been tweaked, so update the associated tests.

Fix tests on nightly

Some output of failing tests have been tweaked, so update the associated tests.

Auto merge of #1828 - fhahn:multiple-package-parameters, r=alexcrichton

This PR for #1528 is still pretty rough (and so far only added multiple package support for tests), but I wanted to make sure the overall approach is fine.

I have made some progress and cargo is now able to compile and execute tests for multiple packages.

In order to execute the doc tests for multiple packages as well, I added `to_doc_test` to `Compilation` (used [here](https://github.com/fhahn/cargo/commit/8b8df3e8d5abfa638852f55730d2f3cb4eec66bc#diff-417e085367d0ce027505dfaa26a089d3R33)). Previously it only executed the doc tests for `Compilation.package`. Another option would be to change `Compilation.package` to be a `Vec<Package>`, because in order to execute the tests of multiple packages, multiple packages are compiled as "top level package". But this would require a changes at a couple of other places.

Use std::env::EXE_SUFFIX in new tests

Add support for multiple -p options to `cargo update`

closes #1528

Add support for multiple -p options to `cargo clean`

Use docopt's new syntax for repeatable options

Add support for multiple -p options to `cargo {bench, build, doc}`